12.4 查询单个终端信息
基本信息
Path： /api/v1/device/query
Method： GET
接口描述：
- 查询终端详细信息。
- 可以基于 externalId 或 mac地址查询终端详细信息，不允许同时传入externalId和mac，否则报错。
- 基于 mac 查询终端详情时，如果匹配到多条数据，则报错。
- 接口适用于 v2.2.9 及以上版本。
请求参数
根据 externalId查询
| 参数名称 | 是否必须 | 示例 | 备注 |
|---|---|---|---|
| externalId | 必须 | 0c4e9039-f81d-11ec-a760-fefcfe545bb7 | 外部ID |
请求示例
/api/v1/device/query?externalId=0c4e9039-f81d-11ec-a760-fefcfe545bb7
根据 mac 查询
| 参数名称 | 是否必须 | 示例 | 备注 |
|---|---|---|---|
| mac | 必须 | FE-FC-FE-21-F5-D1 | mac地址 |
请求示例
/api/v1/device/query?mac=FE-FC-FE-21-F5-D1
返回数据
| 名称 | 类型 | 是否必须 | 默认值 | 备注 | 其他信息 |
|---|---|---|---|---|---|
| code | number | 必须 | 返回码，0 返回成功 | ||
| data | object | 必须 | 报文数据主体 | ||
| ├─ externalId | string | 必须 | 外部ID | ||
| ├─ macList | string[] | 非必须 | MAC地址列表 | ||
| ├─ deviceName | string | 必须 | 终端名称 | ||
| ├─ deviceType | string | 必须 | 设备类型：'PC' PC端，'Mobile' 移动端 | ||
| ├─ assetType | string | 必须 | 资产类型：'CYOD' 企业终端，'BYOD' 个人终端，'COPE' 企业纳管个人终端，'NONE' 未定义 | ||
| ├─ tagList | string[] | 非必须 | 标签列表 | ||
| ├─ deviceBrand | string | 必须 | 品牌 | ||
| ├─ os | string | 必须 | 操作系统 | ||
| ├─ windowsDomain | string | 必须 | windows域控 | 终端加入的域 | |
| ├─ broswer | string | 必须 | 最后接入方式 | ||
| ├─ clientVersion | string | 必须 | 客户端版本 | >=2.2.10 SP3开始支持(2.2.12除外) | |
| ├─ lastNetworkZone | string | 必须 | 最后接入网络区域 | ||
| ├─ lastLoginTime | string | 必须 | 最后接入时间 | ||
| ├─ lastActiveTime | string | 必须 | 终端最后活跃时间 | ||
| ├─ idleTime | number | 必须 | 终端闲置时长（单位：天） | ||
| ├─ onlineStatus | number | 必须 | 在线状态：0 离线 1 在线 | ||
| ├─ loginStatus | number | 必须 | 接入状态：0 未接入 1 已接入 | ||
| ├─ trusted | number | 必须 | 终端授信状态:0 未授信 1 已授信 | ||
| ├─ firstImportTime | string | 必须 | 首次录入时间 | ||
| ├─ lastLoginUser | string | 必须 | 最后登录用户名 | ||
| ├─ displayName | string | 必须 | 最后登录用户显示名 | ||
| ├─ userDescription | string | 必须 | 最后登录用户描述 | ||
| ├─ userDirectoryName | string | 必须 | 最后登录用户所属目录 | ||
| ├─ path | string | 必须 | 最后登录用户所属组织架构 | ||
| ├─ bindUsers | object[] | 非必须 | 绑定用户信息 | ||
| ├─├─ bindUser | string | 非必须 | 用户名 | ||
| ├─├─ bindType | string | 非必须 | 绑定方式：'userSelfBind' 自助绑定，'adminBind' 管理员绑定, 'adminAdmit' 管理员审批 | ||
| ├─├─ bindTime | string | 非必须 | 绑定时间 | ||
| ├─ historyUsers | object[] | 非必须 | 历史登录用户 | ||
| ├─├─ userName | string | 非必须 | 用户名 | ||
| ├─├─ displayName | string | 非必须 | 用户显示名 | ||
| ├─├─ userDescription | string | 非必须 | 用户描述 | ||
| ├─├─ userDirectoryName | string | 非必须 | 用户所属目录名 | ||
| msg | string | 必须 | 返回提示信息，与返回码对应 | ||
| traceId | string | 必须 | 调用链ID，链路请求的标识 |
返回示例
{
"code": 0,
"data": {
"externalId": "0c4e9039-f81d-11ec-a760-fefcfe545bb7",
"macList": ["FE-FC-FE-21-F5-D1", "FE-FC-FE-21-F5-D2"],
"deviceName": "DESKTOP-SDKLASKQ",
"deviceType": "PC",
"assetType": "CYOD",
"tagList": ["开发测试终端", "办公网终端"],
"trusted": 1,
"bindUsers": [
{
"bindUser": "张三",
"bindType": "adminBind",
"bindTime": "2022-06-15 18:35:28",
}, {
"bindUser": "李四",
"bindType": "adminAdmit",
"bindTime": "2022-06-15 18:35:28",
}
],
"historyUsers": [
{
"userName": "user1",
"userDirectoryName": "本地用户目录",
"displayName": "",
"userDescription": ""
},
{
"userName": "t1",
"userDirectoryName": "本地用户目录",
"displayName": "",
"userDescription": ""
}
],
"deviceBrand": "SANGFOR",
"os": "windows 10",
"windowsDomain": "ADDOMAIN1",
"lastLoginUser": "张三",
"displayName": "张三三",
"userDescription": "这是一名本地用户",
"userDirectoryName": "本地用户目录",
"path": "/",
"lastLoginMethod": "Edge/98.0.1108.50",
"clientVersion": "2.2.10.2",
"lastLoginNetZone": "内网IP",
"lastLoginTime": "2022-06-27 14:22:09",
"lastActiveTime": "2022-06-27 14:26:02",
"idleTime": 2,
"onlineStatus": 1,
"loginStatus": 1,
"firstImportTime": "2022-06-24 15:20:26"
},
"msg": "请求成功",
"traceId": "0022c672e4c8b0d6"
}
错误信息
| 错误提示 | 错误码 |
|---|---|
| MAC地址格式错误 | 7201 |
| 外部ID中不能含有非法的特殊字符：换行符，制表符，回车符 | 7201 |
| 外部ID长度超过最大上限：%d | 7201 |
| 请输入匹配参数 | 10000001 |
| 请勿输入多个匹配参数: %s | 10000001 |
| 终端不存在 | 77200001 |
| 匹配到多条终端，请求失败 | 37400404 |